.Dd October 28, 2019
.Dt SWS 1
.Os
.Sh NAME
.Nm sws
.Nd a simple web server
.Sh SYNOPSIS
.Nm
.Op Fl dh
.Op Fl c Ar dir
.Op Fl i Ar address
.Op Fl l Ar file
.Op Fl p Ar port
.Ar dir
.Sh DESCRIPTION
.Nm
is a very simple web server.
It behaves quite like you would expect from any regular web server, in that it
binds to a given port on the given address and waits for incoming HTTP/1.0
requests.
It serves content from the given directory.
That is, any requests for documents is resolved relative to this directory
(the document root).
.Sh OPTIONS
The following options are supported by
.Nm :
.Bl -tag -width i_address__
.It Fl c Ar dir
Allow execution of CGIs from the given directory.
See
.Xr CGIs
for details.
.It Fl d
Enter debugging mode.
That is, do not daemonize, only accept one connection at a time and enable
logging to stdout.
.It Fl h
Print a short usage summary and exit.
.It Fl i Ar address
Bind to the given IPv4 or IPv6 address.
If not provided,
.Nm
will listen on all IPv4 and IPv6 addresses on this host.
.It Fl l Ar file
Log all requests to the given file.
See
.Xr LOGGING
for details.
.It Fl p Ar port
Listen on the given port.
If not provided,
.Nm
will listen on port 8080.
.El
.Sh DETAILS
.Nm
speaks a crippled dialect of HTTP/1.0:
it responds to GET and HEAD requests according to RFC1945, and only
supports the If-Modified-Since Request-Header.
.Pp
When a connection is made,
.Nm
will respond with the appropriate HTTP/1.0 status code and the following
headers:
.Bl -tag -width Last_Modified_
.It Date
The current timestamp in GMT.
.It Server
A string identifying this server and version.
.It Last-Modified
The timestamp in GMT of the file's last modification date.
.It Content-Type
.Ar text/html
or, optionally, the correct content-type for the file in question as
determined via
.Xr magic 5
patterns.
.It Content-Length
The size in bytes of the data returned.
.El
.Pp
If the request type was a GET, then it will subsequently return the data of
the requested file.
After serving the request, the connection is terminated.
.Sh FEATURES
.Nm
supports a number of interesting features:
.Bl -tag -width directory_indexing_
.It CGIs
Execution of CGIs as described in
.Xr CGIs .
.It Directory Indexing
If the request was for a directory and the directory does not contain a file
named "index.html", then
.Nm
will generate a directory index, listing the contents of the directory in
alphanumeric order.
Files starting with a "." are ignored.
.It User Directories
If the request begins with a "~", then the following string up to the first
slash is translated into that user's
.Nm
directory (ie
.Ar /home/<user>/sws/ Ns ).
.El
.Sh CGIs
If a URI begins with the string "/cgi-bin", and the
.Fl c
flag was specified, then the remainder of the resource path will be
resolved relative to the directory specified using this flag.
The resulting file will then be executed and any output generated is
returned instead.
Execution of CGIs follows the specification in RFC3875.
.Sh LOGGING
Per default,
.Nm
does not do any logging.
If explicitly enabled via the
.Fl l
flag,
.Nm
will log every request in a slight variation of Apache's so-called "common"
format: '%a %t "%r" %>s %b'.
That is, it will log:
.Bl -tag -width ____
.It %a
The remote IP address.
.It %t
The time the request was received (in GMT).
.It "%r"
The (quoted) first line of the request.
.It %>s
The status of the request.
.It %b
Size of the response in bytes.
Ie, "Content-Length".
.El
.Pp
Example log lines might look like so:
.Bd -literal -offset indent
155.246.89.8 2019-10-28T12:12:12Z "GET / HTTP/1.0" 200 1406
2001::fe72:3900 2019-10-28T12:12:12Z "GET /file HTTP/1.0" 404 312
.Ed
.Pp
All lines will be appended to the given file unless
.Fl d
was given, in which case all lines will be printed to stdout.
.Sh EXIT STATUS
.Ex -std 
.Sh SEE ALSO
.Xr RFC1945
.Sh HISTORY
A simple http server has been a frequent final project assignment for the
class
.Ar Advanced Programming in the UNIX Environment
at Stevens Institute of Technology.
This variation was first assigned in the Fall 2008 by
.An Jan Schaumann .
